             The Amazing Address Book Demonstration Program
             ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                   Text Version Modules documentation
                   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Introduction
~~~~~~~~~~~~
   In this document I will describe the two modules used by the text version that
runs from the CLI. Specifically the `texty.e' and `address.e' files.

Texty.e Module
--------------
   Yep, silly name. This file handles low-level control of the interface for the
main program. This includes simple things like displaying a message and more
complicated things like reading in a person data instance. Unfortunately the top-
level file for (`address.e')some clarity also requires access to the display, and
as such also has some low-level access of the display - but this module performs
90-99% of the low-level work.

   Some of the procedures are just to display the current situation to the user
and let them know what's going to happen next.(eg remove_display(), show_menu(),
insert_display() and search_display())

   It includes displaying a prompt to the user and getting a response (string)
from them. (get_string()) It includes displaying a person on-screen -
display_person(). And finally getting the user to enter a complete set of
information pertaining to a particular person. These last two have to cycle
through arrays either inputting data into them, or outputting data from them.

That's about it really for that module.


Address.e Main Program file
---------------------------
   This does the `hard' work of binding all the sub-modules together and imposing
some sort of structure onto that binding. For clarity, I have put the main()
procedure at the top of the file to help you understand the program. In the main()
procedure, there is _no_ low-level code except to see if a quit_flag has been set.
The rest of it is procedure calls that are in themselves descriptive. It does the
following:
   It performs some initialisation, displays a menu and gets a choice from the
   user, performs the requested action, and if the user wants to quit, shuts
   down, otherwise it displays the menu, gets a choice and so on.
If you look at the code itself, it is equally readable - if not more so...
The same goes for get_choice(), validate_choice(), do(action), complain(),
insert(), query_delete(), search() & display_it().

   The procedure really(comment), displays the comment and returns TRUE if the
user types any string that contains a 'y' (or Y) in it. The construct
InStr(str,'Y')<>-1 is used to see if the letter `Y' (capitalised) is in str; and
the construct InStr(str,'y')<>-1 is used to see if the letter `y' exists in str.
This will match 'Yes','Yes, please', 'Um, let me think about that, I suppose yes'.
Awkawrdly, 'No way' would also match! Can't win 'em all with one liners...

   The procedure do_search(visit) looks simple, and _is_ simple, but there is one
part of it that needs explaining. The parameter visit is a pointer to a procedure.
That procedure is called every time a matching record is found. That procedure
takes as it's argument a pointer to the person found, which enables you to do what
you like with it - eg display it. That procedure may also return a TRUE value if
it no longer wishes to continue searching for more records. This was done to
enable the search() procedure to be able to use the same code as the remove()
procedure, which also searches, but to do different things with the found people.

   Finally , the remove() procedure checks to see if there's anyone to delete, and
displays a comment if there isn't. Otherwise, it displays a message telling the
user what's about to happen. It then asks the user for a pattern to match against
either a single record or a set of records, and it then performs the search
passing do_search() a pointer to the procedure query_delete(p) which is called for
all records that match the paramters passed. 


Comment
~~~~~~~
   This is a very simple, but robust an readable example, (I feel) of a quarter top
half decent program. I hope it demonstrates some good techniques for programming,
but it's main use is to show the difference between it and the Muse version.

   Bizarrely perhaps however, these two modules/files could be used as the basis
for an ARexx interface for the Muse version since these two files basically deal
strictly with text processing. As with the paint program, I haven't physically had
the time to do this unfortunately!







